<!doctype html>
<html lang="zh-CN">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
    <link rel="stylesheet" href="https://stackpath.bootstrapcdn.com/bootstrap/4.1.3/css/bootstrap.min.css" integrity="sha384-MCw98/SFnGE8fJT3GXwEOngsV7Zt27NXFoaoApmYm81iuXoPkFOJwJ8ERdknLPMO" crossorigin="anonymous">
    <link rel="stylesheet" href="/js/prism.css">
    <link rel="stylesheet" href="/css/app.css">
    <title>Panda api 接口文档工具使用说明 - 叫兽</title>
    <link rel="icon" type="image/x-icon" class="js-site-favicon" href="/img/favicon.ico">
  </head>
  <body>

        <div class="container bg-white pb-5 px-5 spx-0">
            
            <h1 class="post-title">Panda api 接口文档工具使用说明</h1>




            <p>Panda api的接口文档工具是一个简单、易用、又强大的接口文档管理工具。这里我不想讲为什么自己重复造轮子，也不想去讲他有多强大，<code>Talk is cheap, Show you my code.</code>。我们直接从一个例子开始了解他吧。</p><h2>简易快速入门</h2><h3>安装Panda api</h3><p>首先，下载对应系统的安装包，安装Panda api</p><p><a href='/p/2020/1/17/Mac%E4%B8%8B%E5%AE%89%E8%A3%85Panda-Api/'>Mac下的安装包</a>    <br /> <a href='/p/2020/1/17/Mac%E4%B8%8B%E5%AE%89%E8%A3%85Panda-Api/'>Linux下的安装包</a>    <br /> <a href='/p/2020/1/18/Windows%E4%B8%8B%E5%AE%89%E8%A3%85Panda-Api/'>Windows下的安装包</a>  <br /></p><p>下载解压缩后，双击install开头的执行文件，就可以完成安装。</p><p>安装完成后会显示：<pre><code class=".language-shell">Congratulations!
Panda api install done!
You can run pana command in your api docs folder now.
</code></pre></p><p>恭喜，已安装完成。</p><h3>定义一个用户操作的接口文档</h3><p>我们创建一个目录，起名为<code>api&#95;docs</code>(你也可以起你想要的名字)，然后再这个目录中创建<code>auth.json5</code>文件，然后敲上下面的代码</p><pre><code class=".language-json5">{
    name:&quot;用户&quot;,
    desc:&quot;用户登录系统、退出登录系统&quot;,
    order:1,
    apis:
    &#91;{
        name:&quot;用户登录&quot;,
        desc:&quot;用户登录成功，接口会返回一个token&quot;,
        method: &quot;POST&quot;,
        url:&quot;/login/&quot;,
        body&#95;mode:&quot;json&quot;,
        body:{
            username:{name:&quot;用户名&quot;},
            password:{name:&quot;用户登录密码&quot;}
        },
        response:{
            code:{name:&quot;返回结果的代码&quot;, type:&quot;int&quot;, desc:&quot;登录成功只返回1&quot;},
            msg:{name:&quot;登录成功返回消息&quot;, type:&quot;string&quot;, desc:&quot;通常返回都是空&quot;},
            token:{name:&quot;登录成功返回的用户token&quot;, type:&quot;string&quot;, required:false}
        },
        test&#95;data:&#91;
            {
                body:{username:&quot;edison&quot;, password:&quot;123&quot;},
                response:{code:-1, msg:&quot;密码输入不正确&quot;}
            },
            {
                body:{username:&quot;lily&quot;, password:&quot;123&quot;},
                response:{code:-2, msg:&quot;用户名不存在&quot;}
            },
            {
                body:{username:&quot;root&quot;, password:&quot;123&quot;},
                response:{code:1, msg:&quot;登录成功&quot;, token:&quot;5lCadRru&#40;ADn2IE!$LV%x%JF3JNmz&#42;Nf5nFieUG!r&#40;&#40;&amp;esi2CLI$jb!227Lh&quot;}
            },
            {
                body:{username:&quot;lily&quot;},
                response:{code:-1, msg:&quot;密码是必填的&quot;}
            },
            {
                body:{password:&quot;123&quot;},
                response:{code:-1, msg:&quot;用户名是必填的&quot;}
            }
        &#93;
    },
    {
        name:&quot;用户退出登录&quot;,
        method:&quot;GET&quot;,
        url:&quot;/logout/&quot;,
        query:{
            id:{name:&quot;用户id&quot;},
            username:{name:&quot;用户名&quot;}
        },
        response:{
            code:{name:&quot;返回结果的代码&quot;, type:&quot;int&quot;, desc:&quot;退出成功只返回1&quot;},
            msg:{name:&quot;退出操作返回消息&quot;, type:&quot;string&quot;, desc:&quot;通常返回都是空&quot;}
        },
        test&#95;data:&#91;
            {
                query:{id:1, username:&quot;root&quot;},
                response:{code:1, msg:&quot;退出成功&quot;}
            },
            {
                query:{id:3, username:&quot;lily&quot;},
                response:{code:-1, msg:&quot;用户名和id不匹配&quot;}
            },
            {
                response:{code:-1, msg:&quot;必须填写用户名id和用户名&quot;}
            }
        &#93;
    }
&#93;}

</code></pre><p>我们保存好这个文档，在<code>api&#95;docs</code>目录下，运行命令 <code>panda</code>，就会运行起接口文档服务，</p><p>我们就可以在浏览器中输入网址 <code>http://localhost:9000</code>来访问这个文档了。</p><p><code>如果遇到报错</code>，1 请确认是否是在文档目录<code>api&#95;docs/</code>下运行命令；2 如果是端口冲突，可以自行更换端口<code>panda -p 9002</code>，那么你接下来的访问都是<code>http://localhost:9002</code>地址；</p><p>在浏览器打开页面，你将看到下面的页面： <img src="/static/2020/1/panda-api1.png" alt="avatar" /> 然后点击用户看用户的接口文档 <img src="/static/2020/1/panda-api2.png" alt="avatar" /></p><p>✌️耶~！我们拥有了可以在线浏览的接口文档啦！O(∩_∩)O哈哈~！</p><p>继续还有更强大的</p><h3>Panda api可以为前端提供请求服务</h3><p>我们的Panda-api或已经开始为我们的前端提供了接口服务，我们的前端开发人员，或者我们用postman就可以测试请求用户登录接口，也就是用<code>POST</code>方法，请求 <code>http://localhost:9000/login/</code> 这个地址。提交的body参数就是username和password。</p><p>当我们提交post请求，body为：<pre><code class=".language-json">{&quot;username&quot;:&quot;edison&quot;, &quot;password&quot;:&quot;123&quot;}
</code></pre></p><p>我们会得到返回结果<pre><code class=".language-json">{&quot;code&quot;:-1, &quot;msg&quot;:&quot;密码输入不正确&quot;}
</code></pre></p><p>当我们提交post请求，body为：<pre><code class=".language-json">{&quot;username&quot;:&quot;root&quot;, &quot;password&quot;:&quot;123&quot;}
</code></pre></p><p>我们会得到返回结果<pre><code class=".language-json">{&quot;code&quot;:1, &quot;msg&quot;:&quot;登录成功&quot;, &quot;token&quot;:&quot;5lCadRru&#40;ADn2IE!$LV%x%JF3JNmz&#42;Nf5nFieUG!r&#40;&#40;&amp;esi2CLI$jb!227Lh&quot;}
</code></pre></p><p>注意到没，我们请求的参数和返回结果，就是我们再test_data里面设置的数据集，这个数据集中body和response是一一对应的，</p><p>我们前端就可以使用这个数据集进行开发了，测试前端请求和返回的各种不同类型的状态，以及各种各样我们想要的特殊情况，我们还可以继续往里面增加各种测试数据。</p><p><code>注意：</code> 在test_data中的数据匹配规则规则是，从列表第一条数据按顺序往后匹配的，只要前面的数据匹配了，就立即返回。</p><h3>Panda api 自动支持mock</h3><p>当然，Panda api也是支持mock数据的，如果你请求的数据不是test_data数据集里面的数据，你将会得到系统自动mock数据的返回。</p><p>我们提交post请求，body为：<pre><code class=".language-json">{&quot;username&quot;:&quot;hello&quot;, &quot;password&quot;:&quot;123&quot;}
</code></pre></p><p>因为没有test_data数据匹配，就会得到mock数据返回结果<pre><code class=".language-json">{
    &quot;code&quot;: -5217373750860980588,
    &quot;msg&quot;: &quot;3&#94;m&#41;v8TbukaRauosV&quot;
}

// 或者

{
    &quot;code&quot;: 1157384092555109544,
    &quot;msg&quot;: &quot;hJLaTF&amp;75tPnsZ%wSjUp1qr&#126;QwH&quot;,
    &quot;token&quot;: &quot;1JOU0s&#41;sunBOM5!Lo4Ao&quot;
}
</code></pre></p><p>这样的mock数据稍微有点和我们想要的有点差距，我们来改进一下 <code>/login/</code> 接口的 <code>response</code>字段定义<pre><code class=".language-json5">// 这是 原始 response
response:{ 
    code:{name:&quot;返回结果的代码&quot;, type:&quot;int&quot;, desc:&quot;登录成功只返回1&quot;},
    msg:{name:&quot;登录成功返回消息&quot;, type:&quot;string&quot;, desc:&quot;通常返回都是空&quot;},
    token:{name:&quot;登录成功返回的用户token&quot;, type:&quot;string&quot;, required:false}
},

// 改为

response:{
    code:{name:&quot;返回结果的代码&quot;, type:&quot;int&quot;, desc:&quot;登录成功返回1, 登录失败返回-1&quot;, enum:&#91;-1, 1&#93;},
    msg:{name:&quot;登录成功返回消息&quot;, type:&quot;csentence&quot;, desc:&quot;通常返回都是空&quot;},
    token:{name:&quot;登录成功返回的用户token&quot;, type:&quot;string&quot;, required:false, length:60}
},
</code></pre></p><p>保存文件后，直接继续用不在test_data里面的数据请求接口<code>/login/</code>，(当保存好文档，Panda api会自动更新文档数据，瞬间完成，不用手动重启)<pre><code class=".language-json">{&quot;username&quot;:&quot;hello&quot;, &quot;password&quot;:&quot;123&quot;}
</code></pre></p><p>就会得到mock返回结果<pre><code class=".language-json">{
    &quot;code&quot;: 1,
    &quot;msg&quot;: &quot;认管原务给接办例热。&quot;
}

// 或者

{
    &quot;code&quot;: -1,
    &quot;msg&quot;: &quot;权世间素调条中儿白工造种高厂节看县。&quot;,
    &quot;token&quot;: &quot;Vr&amp;B%waOl6i&#40;Uy&#40;o&#126;WWBnA@#80p6&#94;ZnFAW24uYe&amp;dH4&#41;&#41;xmT@dz3&#94;%&amp;SWKBY&quot;
}
</code></pre></p><p>怎么样，更符合我们的需要了吧。 </p><p>我们对<code>code</code>字段，增加了<code>enum</code>属性<code>enum:&#91;-1, 1&#93;</code>，限定了code的值范围只能是<code>-1</code>或者是<code>1</code>里面的其中一个。</p><p>把<code>msg</code>字段的类型<code>type</code>从<code>string</code>改为了<code>csentence</code>，<code>csentence</code>是<code>string</code>的一个子集，表示中文句子，<code>csentence</code>太长太难写了，你也可以使用它的简写<code>cs</code>是一样的</p><p>限定了<code>token</code>字段的长度为60</p><p>下面我们把这个接口文档的每一个部分都详细说明一下</p><h3>接口文档的根字段</h3><p>我们定义了一个用户的接口文档，在接口文档的最根节点有三个字段：<pre><code class=".language-json5">name:&quot;用户操作&quot;,  /&#42; 当前接口文档名称 &#42;/
desc:&quot;用户登录系统、退出登录系统&quot;, /&#42; 当前接口文档描述说明 &#42;/
order:1, /&#42; 表示有多个文档时，当前文档在列表中的排序 &#42;/
apis:&#91;...&#93; /&#42; 当前接口文档的接口列表 &#42;/
</code></pre></p><p>在这个用户操作的接口文档中，我们在apis这个接口列表里面定义了2个接口，用户登录接口和用户退出登录接口，我们先看用户登录接口</p><h3>接口的完整字段</h3><pre><code class=".language-json5">apis:&#91;{
    name:&quot;用户登录&quot;, /&#42; 接口的名称 &#42;/
    desc:&quot;用户登录成功，接口会返回一个token&quot;, /&#42; 接口的描述说明 &#40;可选&#41;，不写时默认为空 &#42;/
    method: &quot;POST&quot;, /&#42; 接口的请求方法 &#40;可选&#41; 不写时默认是GET &#42;/
    url:&quot;/login/&quot;, /&#42; 接口请求的url地址 &#42;/
    auth:false,    /&#42; 是否需要登录， 默认为false &#42;/
    body&#95;mode:&quot;json&quot;, /&#42; 请求的数据格式 &#42;/
    body:{           /&#42; post 请求的 body 字段说明, &#42;/
        username:{name:&quot;用户名&quot;},
        password:{name:&quot;用户登录密码&quot;}
    },
    query:{}, /&#42; url上的query参数（可选） 比如aaa=3&amp;bbb=4 不填写时默认为空 &#42;/
    response:{ // 请求成功后的返回数据结构和字段
        code:{name:&quot;返回结果的代码&quot;, type:&quot;int&quot;, desc:&quot;登录成功只返回1&quot;, enum:&#91;-1, 1&#93;},// 设置了字段类型是int, 增加了code的值范围 是-1或1
        msg:{name:&quot;登录成功返回消息&quot;, type:&quot;csentence&quot;, desc:&quot;通常返回都是空&quot;}, // 字段类型为 csentence， 表示中文句子，也可以使用简写cs
        token:{name:&quot;登录成功返回的用户token&quot;, type:&quot;string&quot;, required:false, length:60} // 限定token的length长度为60
    },
    test&#95;data:&#91;...&#93; // 前端请求和返回的测试用例数据
}&#93;
</code></pre><h3>method</h3><p>其中当请求<code>method</code>是<code>POST</code>的时候，<code>body&#95;mode</code>和<code>body</code>字段设置了才会有效，当请求<code>method</code>是<code>GET</code>的时候，对应的字段是<code>query</code>。</p><p><code>method</code>可以设置为单个方法，例如:<code>method:&quot;POST&quot;</code> 或者 <code>method:&quot;GET&quot;</code>；</p><p><code>method</code>还支持多方法，例如：<code>method:&#91;&quot;GET&quot;, &quot;POST&quot;, &quot;PUT&quot;&#93;</code></p><p>还可以直接设置<code>method</code> 支持所有方法：<code>method:&quot;&#42;&quot;</code></p><p>目前<code>method</code>一共支持的方法有：<code>POST</code>、<code>GET</code>、<code>PUT</code>、<code>DELETE</code>、<code>OPTIONS</code>、<code>PATCH</code>、<code>HEAD</code></p><h3>body 字段</h3><p><code>body</code>表示<code>post</code>的请求<code>body</code>，因为我们定义<code>body&#95;mode</code>是<code>json</code>，因此他必须提交<code>json</code>格式的数据。 body中的第一个字段username的属性是{name:"用户名"}, 这个属性的完整写法是<pre><code class=".language-json5">username:{
    name:&quot;用户名&quot;, /&#42; 字段的名称 &#42;/
    desc:&quot;用户名的描述&quot;, /&#42; 字段的描述说明 &#42;/
    type:&quot;string&quot;, /&#42; 字段的类型， &#40;可选&#41; 不填写时默认是string &#42;/
    required:true, /&#42; 字段是否必填，&#40;可选&#41; 不填写的时候默认是必填 &#42;/
    default:null, /&#42; 字段的默认值，&#40;可选&#41; 不填写时默认是空 &#42;/
    value:null, /&#42; 字段的固定值，&#40;可选&#41; 不填写时默认是空 &#42;/
    enum:&#91;&#93; /&#42; 字段的枚举值，&#40;可选&#41; 表示字段只能从这几个字段中有值，比如&#91;&quot;edison&quot;,&quot;lemon&quot;,&quot;jay&quot;&#93;, 那么username只能是这3个值中的一个 &#42;/
}
</code></pre></p><p><code>enum</code>有两种写法，一种直接就是值: <code>enum:&#91;-1, 1&#93;</code>，或者是值加值的描述 <code>enum:&#91;{&quot;-value&quot;:-1, &quot;-desc&quot;:&quot;失败&quot;}, {&quot;-value&quot;:1, &quot;-desc&quot;:&quot;成功&quot;}&#93;</code> 两种写法的结果是一样的，值只会从-1和1中选取。</p><p>当我们不写<code>desc</code>属性时，默认为空，不写<code>required</code>属性时，默认为true, 也就是这个字段是必填的。</p><h3>type 字段的类型说明</h3><p>type 字段基础类型一共有这几种</p><ol><li>string 字符串 "aaa"</li><li>number 数字 1、2</li><li>bool 布尔值 true、false</li><li>object 对象 {}</li><li>array 数组 []</li></ol><p>除了基础类型，还有更好用的子类型 以及属性的说明 更多在</p><p><a href='/p/2020/1/29/Panda-api%E5%AD%97%E6%AE%B5%E8%AF%B4%E6%98%8E/'>Panda api 字段type类型说明</a></p><h3>response</h3><p>response表示请求后返回的结果字段说明，里面的字段由自己根据前后端约定去定义</p><h3>test_data</h3><p>test_data是非常强大和方便的一个功能，表示前端请求的数据和对应返回的数据集，我们定义好了这个数据集，系统才会接收对应的数据请求，然后返回对应的数据。里面的字段就可以根据真实情况，自己按要求去定义和模拟就好了。</p><p>test_data里面完整的有三个字段<pre><code class=".language-json5">{
    body: {...}, /&#42; request body 请求值， 只在POST请求是才有 &#40;可选&#41; &#42;/
    query:{...}, /&#42; url query 请求值 在POST和GET中都可以有 &#40;可选&#41; &#42;/
    url:&quot;/post/10/&quot;, /&#42; 在接口url是一个正则匹配时，test&#95;data可以指定具体的url匹配 &#42;/
    response:{...} /&#42; 返回结果 &#42;/
}
</code></pre></p><p><a href='/p/2020/1/27/Panda-api-test_data%E5%8C%B9%E9%85%8D%E8%AF%B4%E6%98%8E/'>Panda api test_data匹配说明</a></p><h3>用户退出登录接口</h3><p>我们把用户退出登录接口<code>/logout/</code>的<code>response</code> 的字段也进行了调整，方便mock出更好看的数据。<pre><code class=".language-json5">{
    name:&quot;用户退出登录&quot;,
    method:&quot;GET&quot;, // 使用GET方法请求
    url:&quot;/logout/&quot;,
    query:{ // GET 方法请求的query参数的数据结构字段说明
        id:{name:&quot;用户id&quot;},
        username:{name:&quot;用户名&quot;}
    },
    response:{
        code:{name:&quot;返回结果的代码&quot;, type:&quot;int&quot;, desc:&quot;登录成功只返回1&quot;, enum:&#91;-1, 1&#93;},
        msg:{name:&quot;登录成功返回消息&quot;, type:&quot;csentence&quot;, desc:&quot;通常返回都是空&quot;}
    },
    test&#95;data:&#91;
        {
            query:{id:1, username:&quot;root&quot;},
            response:{code:1, msg:&quot;退出成功&quot;}
        },
        {
            query:{id:3, username:&quot;lily&quot;},
            response:{code:-1, msg:&quot;用户名和id不匹配&quot;}
        },
        {
            response:{code:-1, msg:&quot;必须填写用户名id和用户名&quot;}
        }
    &#93;
}
</code></pre></p><p>这里因为是为了模拟<code>GET</code>请求中的<code>query</code>参数，所以可以加了<code>username</code>和<code>id</code>字段。我们可以看到,当请求<code>method</code>是<code>GET</code>的时候，我们的<code>query</code>参数就要放到<code>query</code>字段中，当然<code>query</code>这个字段的参数在<code>POST</code>请求时也是有效的，你可以同时有<code>body</code>参数和<code>query</code>参数</p><p>在退出登录接口中，因为请求方法是<code>GET</code>, 所以请求参数放到了<code>query</code>中<pre><code class=".language-json5">query:{
    id:{name:&quot;用户id&quot;},
    username:{name:&quot;用户名&quot;}
},
</code></pre></p><p>对应的test_data里面，请求的参数也是query和response对应。</p><p>我们提交<code>GET</code>请求接口<code>/logout/</code>，<code>query</code>为：<pre><code class=".language-json">{&quot;id&quot;:1, &quot;username&quot;:&quot;root&quot;}
</code></pre></p><p>就会得到<code>response</code>结果<pre><code class=".language-json">{&quot;code&quot;:1, &quot;msg&quot;:&quot;退出成功&quot;}
</code></pre></p><p>我们提交<code>GET</code>请求接口<code>/logout/</code>，<code>query</code>为空，啥也不传，请求接口，就会得到<code>response</code>结果<pre><code class=".language-json">{&quot;code&quot;:-1, &quot;msg&quot;:&quot;必须填写用户名id和用户名&quot;}
</code></pre></p><p>我们提交<code>GET</code>请求接口<code>/logout/</code>，<code>query</code>为<pre><code class=".language-json">{&quot;id&quot;:3, &quot;username&quot;:&quot;lily&quot;}
</code></pre></p><p>就会得到<code>response</code>结果<pre><code class=".language-json">{&quot;code&quot;:-1, &quot;msg&quot;:&quot;用户名和id不匹配&quot;}
</code></pre></p><p>我们提交<code>GET</code>请求接口<code>/logout/</code>，<code>query</code>为不是test_data列表里面的值，那么就会得到mock结果<pre><code class=".language-json">{&quot;id&quot;:22, &quot;username&quot;:&quot;lemon&quot;}
</code></pre></p><p>就会得到<code>response</code> mock 结果<pre><code class=".language-json">{
    &quot;code&quot;: 1,
    &quot;msg&quot;: &quot;化认九全准问可信须边切步和太常八权光更书府深始什委设省如消确约领须划存规到方任新数者就世响方许，&quot;
}

// 或者

{
    &quot;code&quot;: -1,
    &quot;msg&quot;: &quot;教文片场必非却电影万些人社进养身新带就选员民先已拉走温件意如做此然价亲种标即格先了江，&quot;
}
</code></pre></p><p><code>注意：</code> 在test_data中有一个数据是没有<code>query</code>参数限制的，这种限制越少的参数要往后面放，test_data的匹配规则是，从列表第一条数据按顺序往后匹配的，只要前面的数据匹配了，就立即返回。</p><h3>设置项目的概要</h3><p>创建文件<code>&#95;settings.json5</code>，敲上下面的内容。(注意，文件名开头有一个下划线，主要是为了把他和正常的接口文档区分开)<pre><code class=".language-json5">{
  project&#95;name: &quot;Panda Api&quot;, /&#42; 项目名称 &#42;/
  project&#95;desc: &quot;Panda Api is a simple api manage tool&quot; /&#42; 项目简述 &#42;/
}
</code></pre></p><h3>设置项目首页说明</h3><p>创建文件 <code>README.md</code>，<pre><code class=".language-json">
# Hello Panda api

大家好，我是一个项目说明文档

</code></pre></p><p>整个项目的全部desc字段和 README.md文件里面的内容都是支持markdown语法的。</p><p>原生json5语法是字符串换行的，也支持//注释和/<em> 注释 </em>/, 你可以这么写：</p><pre><code class=".language-json">&quot;desc&quot;:&quot;##说明文档  
1 aaaa  
2 bbbbb  
3 ccccc  
&quot;
</code></pre><p><a href='/p/2020/2/5/json5/'>json5语法说明</a></p><h3>列表和对象</h3><p>获取文章列表接口</p><pre><code class=".language-json5">{
    name:&quot;文章列表&quot;,
    method:&quot;GET&quot;,
    url:&quot;/post/star/list/&quot;,
    query:{
        page:{name:&quot;分页&quot;, type:&quot;number&quot;}
    },
    response:{
        total&#95;page: {name:&quot;总页数&quot;, type:&quot;number&quot;},
        total&#95;count: {name:&quot;总记录数&quot;, type:&quot;number&quot;},
        current&#95;page: {name:&quot;当前页码&quot;, type:&quot;number&quot;},
        result: 
            &#91;{
                &quot;-name&quot;:&quot;文章列表&quot;,
                &quot;-desc&quot;:&quot;只包含用户点赞过的文章列表&quot;,
                id: {name:&quot;用户id&quot;, type:&quot;number&quot;},
                title: {name:&quot;文章标题&quot;},
                category: {
                    &quot;-name&quot;:&quot;文章所属分类&quot;,
                    &quot;-desc&quot;:&quot;这里为了体现对象，所以就特意把文章分类用一个对象来表示&quot;,
                    id:{name:&quot;分类id&quot;, type:&quot;number&quot;},
                    name:{name:&quot;分类名称&quot;, type:&quot;string&quot;}
                },
                content: {name:&quot;文章内容&quot;},
                created: {name:&quot;文章创建时间&quot;, type:&quot;number&quot;}
            }&#93;
    }
}
</code></pre><p>这个例子中，<code>response</code>返回的结果中，<code>result</code>字段，还有一点特殊，他是一个列表，然后列表里面有一个对象，他表示<code>result</code>的类型是<code>array</code>,然后里面的那个对象描述的是<code>array</code>中的数据的展现类型，字段有哪些。</p><p><code>result</code>中的最开头 <code>-name</code> 字段和<code>-desc</code>字段是用来描述<code>result</code>字段的名称和描述。因为为了防止和常规字段冲突，所以在前面加了<code>-</code>减号, </p><p>系统会根据<code>&#91;&#93;</code>自动识别<code>result</code>是一个数组，而且人阅读起来也很友好，因此不再需要标注类型</p><p><code>category</code>字段的类型是一个对象<code>object</code>， 里面有两个属性<code>id</code>和<code>name</code>，分别表示分类的id和分类的名称。同样的<code>-name</code>, <code>-desc</code>是用来描述<code>category</code>这个字段的。系统也会自动识别出<code>object</code>对象，因此不需要人工标注类型</p><h3>注意事项</h3><p>如果不同的接口，同一个<code>url</code>, 但是请求方法不同，有<code>GET</code>,有<code>POST</code>是允许的。你可以为每一种方法定义不同的接口</p><p>如果不同的接口，同一个<code>url</code>, 请求方法也相同，都是<code>GET</code>或者都是<code>POST</code>，那么系统会判定，只允许一个，前面的会被后面的覆盖。</p><p>教程中的代码在这里： <a href='https://github.com/arlicle/panda-api-examples/tree/master/simple'>https://github.com/arlicle/panda-api-examples/tree/master/simple</a></p><h3>结尾</h3><p>至此，我们的建议教学就结束了，可以试着找一个以前的项目或者新项目，开始写自己的接口文档，遇到有任何的问题或者意见建议，欢迎和我讨论。</p><p>下一篇，开启高级教学，一些复杂的用法，以及代码和数据的重用，让我们更简单快速的维护接口文档。</p><p><a href='/p/2020/1/15/Panda-api%E9%AB%98%E7%BA%A7%E4%BD%BF%E7%94%A8%E8%AF%B4%E6%98%8E/'>Panda-api高级使用说明</a></p>
            <p class="text-left text-muted">2020-02-05 07:50</p>
        </div>
        <div class="container">
            <div class="row mt-4">
                <div class="col-6 text-left"><a href="/p/2020/1/15/Panda-api高级使用说明/">上一篇: Panda api 高级使用说明</a></div>
                <div class="col-6 text-right"><a href="/p/2020/1/4/设计一个接口管理工具/">下一篇:设计一个方便前后端分离项目开发的接口管理工具</a></div>
            </div>
        </div>

        <button class="btn btn-link m-menu-toggle d-md-none fixed-top collapsed" type="button" data-toggle="collapse" data-target="#m-menu" aria-controls="m-menu" aria-expanded="false" aria-label="Toggle docs navigation"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 30 30" width="30" height="30" focusable="false"><title>Menu</title><path stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-miterlimit="10" d="M4 7h22M4 15h22M4 23h22"></path></svg>
        </button>
        <ul class="nav flex-column collapse fixed-top site-menu d-md-block" id="m-menu">
            <li class="nav-item">
                <a class="nav-link" href="/">首页</a>
            </li>
            <li class="nav-item">
                <a class="nav-link" href="/p/list/">所有文章</a>
            </li>
            <li class="nav-item">
                <a class="nav-link" href="/p/about-me/">关于我</a>
            </li>
            <li class="nav-item">
              <a class="nav-link" href="https://github.com/arlicle">Github</a>
          </li>
        </ul>

        
    <div class="container mt-5">
        <h3>留言</h3>
        <div id="commentApp"></div>
    </div>
    <script>
        var AL_configs = {
            "post_id":"/p/2020/1/15/Panda-api使用说明/",
            "appid":"847e226e8a46f64045d45312245a68ba1368a564"
        };
        (function() {
            var hm = document.createElement("script");
            hm.src = "https://comment.debugmyself.com/sc.js";
            var s = document.getElementsByTagName("script")[0];
            s.parentNode.insertBefore(hm, s);
        })();
    </script>


        <footer class="footer mt-5 pb-2">
        <div class="container text-center">
          
          <p><span class="text-black-50">Powered by <a href="https://github.com/arlicle/ablog">ablog</a> © 2019 叫兽</span></p>
          <p><span class="text-black-50"><a href="http://www.beian.miit.gov.cn/">滇ICP备10201832号-3</a></span></p>
          
        </div>
        </footer>
        <script src="https://code.jquery.com/jquery-3.3.1.slim.min.js" integrity="sha384-q8i/X+965DzO0rT7abK41JStQIAqVgRVzpbzo5smXKp4YfRvH+8abtTE1Pi6jizo" crossorigin="anonymous"></script>
        <script src="https://cdnjs.cloudflare.com/ajax/libs/popper.js/1.14.3/umd/popper.min.js" integrity="sha384-ZMP7rVo3mIykV+2+9J3UJ46jBk0WLaUAdn689aCwoqbBJiSnjAK/l8WvCWPIPm49" crossorigin="anonymous"></script>
        <script src="https://stackpath.bootstrapcdn.com/bootstrap/4.1.3/js/bootstrap.min.js" integrity="sha384-ChfqqxuZUCnJSK3+MXmPNIyE6ZbWh2IMqE241rYiqJxyMiZ6OW/JmZQ5stwEULTy" crossorigin="anonymous"></script>
        <script src="/js/prism.js"></script>
        <script>
        $(function () {
            $('[data-toggle="tooltip"]').tooltip();
        })
        </script>
        <script type="text/x-mathjax-config">
        MathJax.Hub.Config({tex2jax: {inlineMath: [['$','$'], ['\\(','\\)']]}, displayAlign: "left",scale: 180});
        </script>
        <script type="text/javascript" async
        src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.5/MathJax.js?config=TeX-MML-AM_SVG" async>
        </script>
  </body>
</html>